home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1998 June / SGI Freeware 1998 June.iso / dist / fw_python.idb / usr / freeware / catman / u_man / cat1 / chapter.Z / chapter
Encoding:
Text File  |  1997-09-09  |  7.9 KB  |  242 lines
  1.      Tech    Chapter          1           -    Relation    format
  2.      MetalBase                               5.1
  3.      -------------------------------------------------------------------------------
  4.  
  5.      MetalBase    keeps  track  of  all  data  in     a  single  file (.REL
  6.      extension), with
  7.     the exception of multi-length fields--data for those is    stored
  8.      in    a second
  9.     file (.DAT extension).
  10.  
  11.      The .REL file consists of a  header  containing  descriptions  of
  12.      fields and
  13.     indices, followed by any number    of fixed-length    records.  Each
  14.      record
  15.     actually consists of index information for a  tuple,  followed
  16.      by    a tuple's
  17.     record data (for each multi-length  field,  a  pointer    to  an
  18.      offset in the
  19.     .DAT file is stored).
  20.  
  21.  
  22.      FIELD                             TYPES
  23.      -------------------------------------------------------------------
  24.  
  25.      Each field    in a record is one of a     number     of  intrinsic    types;
  26.      user-defined
  27.     types aren't supported (I was gonna put    that in    4.1, but never
  28.      bothered.
  29.     I'm glad I didn't now).     Valid field types are:
  30.  
  31.        Enum    Name    Storage       Typedef From          Expected length
  32.        -----------    ---------  -----------------  ---------------
  33.        T_CHAR.......char [].......................any (fixed)**
  34.        T_SHORT......short.........................two bytes
  35.        T_USHORT.....ushort.....unsigned short.....two bytes
  36.        T_LONG.......long..........................four bytes
  37.        T_ULONG......ulong......unsigned long......four bytes
  38.        T_FLOAT......float.........................four bytes
  39.        T_DOUBLE.....double........................eight bytes
  40.        T_MONEY......double........................eight bytes
  41.        T_TIME.......mb_time....long...............four bytes
  42.        T_DATE.......mb_date....long...............four bytes
  43.        T_SERIAL.....long..........................four bytes
  44.        T_PHONE......mb_phone...struct mb_phone....varies (fixed)*
  45.        T_BYTE.......byte []....unsigned char []...any (fixed)**
  46.        T_MCHAR......mchar......struct mchar.......varies (fixed)*
  47.        T_MBYTE......mbyte......struct mbyte.......varies (fixed)*
  48.  
  49.      * the length of these fields depends on the structure-packing
  50.        algorithm used by the local compiler.
  51.  
  52.     ** the length of these fields is decided when the relation is
  53.        first built,    and remains constant for each record.
  54.  
  55.  
  56.      FIELD                          DESCRIPTIONS
  57.      ------------------------------------------------------------
  58.  
  59.  
  60.      T_MCHAR, T_MBYTE:
  61.     See  the  chapter  on  multi-length  fields  for  an  in-depth
  62.      description of how
  63.     these fields are implemented.
  64.  
  65.  
  66.      T_TIME and    T_DATE:
  67.     These fields are stored    as longs;  information    is  stored  in
  68.      such an order
  69.     that more relevant information is stored  in  higher  bits--in
  70.      this way,
  71.     these fields can be sorted as if they were of type T_LONG  and
  72.      will
  73.     be sorted meaningfully even when parsed.
  74.  
  75.     Bits in    time field:
  76.        00000000     hhhhhmmm      mmmsssss         suuuuuuu        --
  77.      h=hour,m=min,s=sec,u=microseconds
  78.  
  79.     Bits in    date field:
  80.        00000000 00yyyyyy yyyyyyym mmmddddd --y=year,m=month,d=day
  81.  
  82.  
  83.      T_MONEY:
  84.     Money is treated exactly  as  double,  but  is    rounded     to  2
  85.      decimal places
  86.     before being written or    compared.  MetalBase releases prior to
  87.      5.1 used
  88.     the obvious algorithm for this--
  89.  
  90.          X = floor ( (long)(X *    100.0) ) / 100.0
  91.  
  92.     --but this doesn't work    on most    systems     (it  introduces  huge
  93.      floating-point
  94.     problems--try, for example, 34.16 in a T_MONEY field in     5.0).
  95.      Sad state of
  96.     the world.  The    routine    "double    tomoney     (double);"  has  been
  97.      provided with
  98.     release    5.1 to correct this problem.
  99.  
  100.  
  101.      T_SERIAL:
  102.     Serial fields  are  T_LONGs  which  are     automatically    filled
  103.      before a call to
  104.     mb_add() or mb_add_q().     Calls to  mb_upd()  verify  that  the
  105.      value of these
  106.     fields has not changed since  the  record  being  updated  was
  107.      first retrieved;
  108.     in this    way, each record can  be  stamped  with     an  indelible
  109.      number.  The first
  110.     serial value assigned will be zero unless specified  otherwise
  111.      during
  112.     creation of the    relation; it is    incremented on each successive
  113.      add, and
  114.     never decremented (even    if a record is deleted).
  115.  
  116.  
  117.      T_PHONE:
  118.     In MetalBase 5.0, phone     number     fields     were  stored  as  20-
  119.      character fields
  120.     which were formatted into a fixed form    before    being  stored.
  121.      MetalBase 5.1,
  122.     and hopefully all later    versions, use a     structure  consisting
  123.      of    three
  124.     shorts    (area  code,  prefix  and   number)   and   one      long
  125.      (extension).
  126.  
  127.  
  128.      T_BYTE:
  129.     These are used just about like char, save that    if  you     index
  130.      them, searches
  131.     won't stop at the first    zero in    the string (as they would  for
  132.      strings).
  133.     The routines hextostr()    and strtohex() are  used  by  MB_INPUT
  134.      for data-entry
  135.     of byte    fields.
  136.  
  137.  
  138.      RELATION                            FORMAT
  139.      ---------------------------------------------------------------
  140.  
  141.  
  142.     Pos  #/Bytes   Description
  143.  
  144.       0    1.......(char)51    : 5.1 signature
  145.       1    1.......Bit 1: Work flag    -- set if  relation  is     being
  146.      updated
  147.                Bit 2: fMulti    -- set if relation has    multi-
  148.      length fields
  149.                Bit 3: fCorrupt    -- set if relation  was     found
  150.      to    be corrupt
  151.       2    4.......Number of unindexed records
  152.       6    4.......Pointer to fields' decriptions  => :A
  153.      10    4.......Pointer to indices' decriptions => :B
  154.      14    4.......Pointer to record 0           => :C
  155.      18    4.......Number of records
  156.      22    4.......Next serial field value
  157.      26    2.......Number of fields
  158.      28    2.......Number of indices
  159.      30    4*I.....Pointers    to index-heading records  (top    record
  160.      in    each tree)
  161.  
  162.      A:    var*F...Fields' descriptions:
  163.               byte      0 : Type (0-10, as listed above)
  164.               bytes    1-2 : Size (short/ used    only for  char
  165.      fields)
  166.               bytes    3-? : Name (max    len =  20,  terminated
  167.      by    '|')
  168.  
  169.      B:    var*I...Indices'    descriptions:
  170.               byte      0 : Type (0-1, 0==nodups, 1==dups)
  171.               bytes      1 : Number of    fields in this index
  172.               bytes    2-? : Name (max    len =  20,  terminated
  173.      by    ':')
  174.                 --- : Each field's  sequential    #  (as
  175.      short, 0-based)
  176.  
  177.      ?:    1.......(char)1 if encryption mask chosen yet;  (char)0
  178.      if    not
  179.      ?:    1.......Encryption mask;    0 indicates no encryption
  180.      ?:    126.....Unused since 5.0    (reserved space    for  later  MB
  181.      versions)
  182.      ?:    1.......Separator ('0)
  183.  
  184.      C:    var*R...Records:
  185.               13 bytes for each index: Index information
  186.                  Bytes  0-3    : Left-child (record #)
  187.                  Bytes  4-7    : Right-child (record #)
  188.                  Bytes 8-11    : Parent (record #)
  189.                  Byte    12    : Balance (';'=-2 '<'=-1 '='=0
  190.      '>'=1 '?'=2)
  191.               recsize bytes    : Record information (no field
  192.      separators)
  193.               1 byte separator ('0)
  194.  
  195.      D:    var*R...Unindexed records:
  196.               13 zeroes for    each index, reserved for later
  197.      indexing
  198.               recsize bytes: Record    information (no     field
  199.      separators)
  200.               1 byte separator ('0)
  201.  
  202.  
  203.      Actual record  information     is  stored  as     it  looks  in    memory
  204.      structures; thus,
  205.     relations will not be portable    between     machines  unless  the
  206.      same structure-
  207.     packing    algorithm is used on both systems.
  208.  
  209.  
  210.      DATA-FILE                            FORMAT
  211.      --------------------------------------------------------------
  212.  
  213.  
  214.     Pos  #/Bytes   Description
  215.  
  216.       0    1.......(char)51    : 5.1 signature
  217.       1    4.......offset of first free-space chain    link
  218.  
  219.      The chapter on multi-length fields    describes the use of this file
  220.      in    more
  221.     detail.     Essentially, the .DAT file is a threaded heap,     where
  222.      only the
  223.     scattered blocks of free space are chained.  The  byte-offsets
  224.      of    "used"
  225.     blocks are stored in  the  .REL     file  as  pointers  to     data;
  226.      however, the .DAT
  227.     file has no such link back to the appropriate  record  numbers
  228.      in    the .REL
  229.     file.  This was    done  for  performance    reasons,  and  doesn't
  230.      really impact
  231.     the recovery of    data within corrupt .REL/.DAT files (as    you're
  232.      basically
  233.     hosed anyway if    things get bad).
  234.  
  235.     Pos  #/Bytes   Description
  236.  
  237.     n+0    4.......byte-offset of next link    in the free chain,  or
  238.      0L    if at end
  239.     n+4    4.......number of bytes in this block, including     these
  240.      8
  241.  
  242.